home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 17 / AMIGAplus Sonderheft 17 (1999)(ICP)(DE)[!].iso / PD / Anwendungen / -DataTypes- / mpegvideo / mpegvideo.datatype.doc < prev    next >
Text File  |  1998-06-17  |  54KB  |  1,277 lines
  1. TABLE OF CONTENTS
  2.  
  3. mpegvideo.datatype/--datasheed--
  4. mpegvideo.datatype/ADTM_LOADFRAME
  5. mpegvideo.datatype/ADTM_UNLOADFRAME
  6. mpegvideo.datatype/DTM_WRITE
  7. mpegvideo.datatype/MAIN
  8. mpegvideo.datatype/OM_DISPOSE
  9. mpegvideo.datatype/OM_NEW
  10. mpegvideo.datatype/preferences
  11. mpegvideo.datatype/--datasheed--             mpegvideo.datatype/--datasheed--
  12.  
  13.    NAME
  14.        mpegvideo.datatype -- data type for mpeg video streams
  15.  
  16.    SUPERCLASS
  17.        animation.datatype
  18.  
  19.    DESCRIPTION
  20.        The mpegvideo data type, a sub-class of the animation.datatype, is
  21.        used to load, play and save (encode) mpeg 1 and mpeg 2 video
  22.        streams.
  23.  
  24.    METHODS
  25.        OM_NEW -- Create a new animation object from a description file. The
  26.            source may a file or no source (e.g. an empty object created
  27.            with DTST_RAM for encoding etc.).
  28.  
  29.        OM_DISPOSE -- Dispose instance and contents (frames, colormaps etc.),
  30.            then pass msg to superclass
  31.  
  32.        OM_UPDATE -- Perform an ICM_CHECKLOOP check, and if succesfull, the
  33.            method will be executed like OM_SET downstairs.
  34.  
  35.        OM_SET -- Pass msg to superclass, and if the mpegvideo.datatype
  36.            instance is the "top instance", call GM_RENDER if retval from
  37.            superclass was != 0UL.
  38.  
  39.        DTM_WRITE -- Saves either the local (RAW) format, which is
  40.            a MPEG1/2-Video-stream, or passes the message to superclass
  41.            (which saves the current frame as an IFF ILBM picture).
  42.  
  43.        ADTM_LOADFRAME -- Fill in struct adtFrame with requested information
  44.            from internal FrameNode list like bitmap, colormap, samples, etc.
  45.  
  46.        ADTM_UNLOADFRAME -- Release resources obtained in a successfull or
  47.            unsuccessfull call to ADTM_LOADFRAME.
  48.  
  49.        All other methods are passed unchanged to superclass.
  50.  
  51.    ATTRIBUTES
  52.        Following attributes are set by the object and are READ-ONLY for
  53.        applications:
  54.        DTA_NominalHoriz      -- same as ADTA_Width
  55.        DTA_NominalVert       -- same as ADTA_Height
  56.        DTA_ObjName           -- same as DTA_Name
  57.        ADTA_Width            -- set by video stream
  58.        ADTA_Height           -- set by video stream
  59.        ADTA_Depth            -- set by video stream (or by prefs)
  60.        ADTA_NumColors        -- set by ADTA_Depth or to the num. of
  61.                                 palette entries
  62.        ADTA_ColorRegisters   -- obj's palette with ADTA_NumColors entries
  63.        ADTA_CRegs            -- obj's palette with ADTA_NumColors entries
  64.        ADTA_Frames           -- total number of frames
  65.        ADTA_FramesPerSecond  -- set by video stream
  66.        ADTA_ModeID           -- calculated internally or set by prefs
  67.        ADTA_KeyFrame         -- key frame
  68.        ADTA_Sample           -- sample (optional, if a sample is attached)
  69.        ADTA_SampleLength     -- sample length (for one timestamp/see above)
  70.        ADTA_Period           -- sample period (optional, see ADTA_Sample)
  71.        ADTA_Volume           -- sample volume (optional, see ADTA_Sample)
  72.        ADTA_Cycles           -- 1UL
  73.  
  74.    BUGS
  75.        - animation.datatype >= V41.3 is preferred...
  76.          WARNING: NOLOADALL mode MUST NOT be used with animation.datatype
  77.          V40 (it's safe, but...).
  78.  
  79.        - EHB, COLOR, and GRAY dithering are broken
  80.  
  81.        - YUV420 dithering (using Picasso 96 yuv-bitmaps) isn't tested yet.
  82.  
  83.        - The DEVICE option for using a cd32mpeg.device-compatible device for
  84.          decoding isn't tested yet.
  85.  
  86.        - NOLOADALL mode has some funny effects: If you press the play button,
  87.          I'll take some time until playback starts. This is caused
  88.          by animation.datatype which pre-fetches the first ~10 frames
  89.          before starting the playback. This is not a bug !
  90.          The PPC version should not have this problem.
  91.  
  92.        - NOLOADALL mode does not work with the most mpeg2-streams
  93.          (no interlace support in NOLOADALL mode).
  94.  
  95.        - NOLOADALL mode has problems with loading the last frame sequence.
  96.  
  97.        - Index generation in NOLOADALL mode is buggy, which results
  98.          in a (somtimes) very confused decoder.
  99.          (I-Frame-ONLY streams should work perfectly...).
  100.  
  101.        - In interlaced mpeg streams (mpeg 2 only) the first frame isn't
  102.          decoded properly.
  103.  
  104.        - Interlaced mpeg streams (mpeg 2 only) cannot be scaled properly
  105.          using the WIDTH and HEIGHT prefs options.
  106.  
  107.        - The DITHERATPLAYBACKTIME causes that the key frame is not filled
  108.          with the initial frame data at OM_NEW time.
  109.  
  110.        - The datatype allocates much more memory than really used.
  111.  
  112.        - In large videos, the frames at the end will be played slower than
  113.          those at the beginning of the file. This is the result of the
  114.          sequential search internally used (only serious with more than
  115.          25000 frames (mc68030/50mhz)) for scanning the internal index list.
  116.          Will be fixed.
  117.  
  118.        - CyberGFX 24 bit output mode uses 32 bit ARGB bitmaps, but the A
  119.          (alpha) byte is not set to 0xFF (visible), instead it is set to 0.
  120.          The same for 15 bit output mode, where the MSB is a alpha mask bit.
  121.  
  122.        - If you don't have my "paranimdtcpatch" patch running,
  123.          animation.datatype (animation.datatype 40.7 (28.09.93)) subclasses
  124.          will suffer under timing problems when two or more
  125.          animation.datatype objetcs are playing. I've released a matching
  126.          patch, DON'T blame me for this bug. Any comments for this problem
  127.          should be related  to the "paranimdtcpatch" project.
  128.          "paranimdtcpatch" is available in the aminet
  129.          ("util/dtype/panimdtcptch012.LhA").
  130.          NOTE that animation.datatype V41 does NOT require the patch
  131.          anymore.
  132.  
  133.        - The encoder aligns the width of the animation to be divisible by
  134.          two.
  135.  
  136.        - The PPC version is slow because both (m68k and PPC) caches
  137.          are flushed for each AmigaOS call, which slows down the thing
  138.          significantly.
  139.  
  140.        - NOBFRAMES / NOPFRAMES option seems to slow down the decoder
  141.          (unneccesary) due an inefficient piece in the bit parsing code.
  142.          Will be fixed soon.
  143.  
  144.        - The duration values in the ADTM_LOADFRAME/struct adtFrame message
  145.          are not correct. The duration value belongs to the previous frame.
  146.          Due the fact that the duration value is mainly the same (skipping
  147.          B frames means (normally) that everytimes the same number of
  148.          frames is skiped), this is not a problem (yet) for the NOBFRAMES
  149.          option and MPEG-1.
  150.          Will be fixed soon.
  151.  
  152.        - The PPC version sometimes hangs with ppc.library V45.20.
  153.          Try a later ppc.library version.
  154.  
  155.    TODO
  156.        - Code cleanup
  157.  
  158.        - Bug fixing
  159.  
  160.        - Writing an amigaguide document
  161.  
  162.        - Support for 24 bit planar bitmaps in the encoder
  163.  
  164.        - Interleaved planar bitmap output
  165.  
  166.        - Update the IDCT to avoid unneccesary table accesses.
  167.  
  168.    HISTORY
  169.        V2.1
  170.          First testing release, mainly to find some bugs...
  171.  
  172.        V2.2
  173.          - ADTA_SampleLength calculations were wrong. The value was got
  174.            from the first frame. Now the value is set correctly to
  175.            alf_SampleLength / (alf_Duration + 1)
  176.            Fixed.
  177.  
  178.          - The encoder (and maybe other parts) did not like planar
  179.            interleaved bitmaps because the internal CopyBitMap
  180.            function expected evertimes a non-interleaved bitmap.
  181.            (I replaced the functions with the functions used in
  182.            animation.datatype V41.5 to fix the bug...).
  183.            Fixed.
  184.  
  185.          - If a ADTM_LOADFRAME method gets a message from a previous
  186.            ADTM_LOADFRAME call, the contents are freed now after
  187.            the requested data have been loaded. This avoids the
  188.            pathological case that if the same frame (or one from a
  189.            matching IBBP...I sequence) should be freed and returned
  190.            the frame IS freed and then re-loaded.
  191.            Now the free of the given frame is done after the loading
  192.            of the requested frame which avoids this inefficienty.
  193.  
  194.          - The encoder is now faster during loading of frames because
  195.            it now processes and converts RGB -> YUV line by line
  196.            instead of block by block base.
  197.            The reason is that the new way uses a cache more efficient
  198.            then the previous method.
  199.  
  200.          - Decreased the minimum decoder buffer size down to 2048 bytes,
  201.            which makes the progress gauge more accurate for small files.
  202.  
  203.          - Fixed the bug that the encoder treats mpeg timestamp as
  204.            animation.datatype timestamp. Now the conversion is donre using
  205.            animdtc_timestamp = mpeg_frame_ts /
  206.                                (mpeg_frame_rate / ADTA_FramesPerSecond);
  207.            Fixed.
  208.  
  209.          - The encoder now allocates some resouces once in the init setup
  210.            instead of allocating/freeing them per-frame.
  211.  
  212.          - Fixed the bug that if the loading of a frame failed that this
  213.            frame wasn't free'd using ADTM_UNLOADFRAME.
  214.  
  215.          - The encoder now recognizes ADTM_Frame (startframe) and
  216.            ADTM_Frames (number of frames to encode).
  217.  
  218.          - The encoder now supports palette-per-frame, e.g. colormap
  219.            changes in the source animation.
  220.  
  221.          - The encoder now uses "realloc" like-loading from source object
  222.            (e.g. that ADTM_LOADFRAME can re-use the data from a previous
  223.            ADTM_LOADFRAME call).
  224.            This can be turned off using the ENC_NO_REALLOC_LOADFRAME prefs
  225.            switch.
  226.  
  227.          - Implemented frame rate code 9. The XING products use this rate
  228.            code as 15 fps.
  229.  
  230.          - The encoder now selects the "best" FPS rate, e.g. which mpeg fps
  231.            rate is the nearest to the source fps rate.
  232.            This includes the rate code 9 (XING 15 fps rate code) !
  233.  
  234.          - Fixed the default ENC_BIT_RATE value. It now defaults to
  235.            (ADTA_Width * ADTA_Height * 24 * mpeg_fps) / 52.8,
  236.            which results in 1152000.0 bits/s for 352 * 288 (SIF) display.
  237.            (e.g. the default compression ration is 52.8).
  238.            Fixed.
  239.  
  240.          - If CyberGFX is active some output formats now create
  241.            chunkypixel output (currently ORDERED and GRAY output mode
  242.            which create LUT8 bitmaps in this case).
  243.            (Suggested by Ralf Heinert (frodo@w-specht.rhein-ruhr.de)).
  244.  
  245.          - Implemented MONO and MONO_THRESHOLD dithering. Interlaced
  246.            MPEG streams are not supported yet.
  247.  
  248.          - Little speedup for all dithering modes which use the Y data
  249.            only (MONO#? and GRAY dithering, ORDERED dithering if
  250.            CR_RANGE and CB_RANGE are both 1).
  251.  
  252.          - CyberGFX bitmap output in conjunction with the USEVMM switch
  253.            now forces the DITHERATPLAYBACKTIME switch to be sure that
  254.            the datatype really uses VMM memory to cache frame data.
  255.  
  256.          - If no prefs-file is found, a warning is printed and VERBOSE
  257.            mode is forced.
  258.            This should avoid some emails like "I didn't know that the
  259.            datatype has a prefs-file...".
  260.  
  261.          - Ported the whole datatype to the PPC environment:
  262.            - All structures shared between m68k and PPC side have
  263.              been padded to get the same size and offsets for all
  264.              structure members. A small C program which prints
  265.              the offsets was used for fiddeling out these things.
  266.  
  267.            - I introduced some own library functions to pack multiple
  268.              AmigaOS calls into one PPCCallOS-call to save cache
  269.              flushing cycles.
  270.  
  271.            - Extensive testing to get rid of some little problem.
  272.  
  273.            - Wrote some interface functions for PPC task support.
  274.  
  275.          - Removed some table accesses, removed and updated some parts
  276.            to match the SAS/C PPC needs.
  277.  
  278.          - Frank Mariak (fmariak@chaosengine.ping.de) ported the HAM
  279.            code from m68k assember to C that this can be used on the
  280.            PPC side.
  281.            Thanks !
  282.  
  283.          - Fixed a bug in the encoder's motion estimation section
  284.            which caused quality loss.
  285.            Fixed.
  286.  
  287.        V2.3
  288.          - PPC version recompiled with SAS/C PPC beta 14.
  289.  
  290.          - Switched to ppc.library V45.9, which fixes some problems in
  291.            the PPCCallOS function...
  292.  
  293.          - Optimized some PPC AmigaOS stub functions by hand to get more
  294.            speed; replaced some functions by their PPC kernel equivalents
  295.            for the same reason.
  296.  
  297.          - Chunkypixel bitmap allocation (AllocBitMap) now gets the
  298.            ADTA_KeyFrame keyframe bitmap as parameter.
  299.            Maybe, the RTG software can do something usefull with this
  300.            hint...
  301.  
  302.          - Fixed HAM dithering code. The used abs()-macro was wrong,
  303.            I replaced it with SAS/C build-in abs macro call.
  304.            Thanks to Frank Mariak (fmariak@chaosengine.ping.de) for
  305.            fixing the bug.
  306.            Fixed.
  307.  
  308.          - Major speed up in the YUV420 and YUV 422 non-interlaced ->
  309.            truecolor code
  310.            I seperated both parts to get the maximum performance in both
  311.            parts.
  312.  
  313.          - Fixed a bug in the interlaced remapping section (MPEG-2 only)
  314.            which caused the display jittering more than "required".
  315.            Fixed.
  316.  
  317.          - Fixed a bug in the "smakefile" which caused that the autodoc
  318.            file "mpegvideo.datatype.doc" missed the "preferences"
  319.            section and other things...
  320.            Thanks to Frederic Steinfeld (fsteine@iiic.ethz.ch) for reporting
  321.            the problem...
  322.            Fixed.
  323.  
  324.          - Minor fixes in the autodocs.
  325.  
  326.          - Speedup in the CyberGFX output modes: The dither routines now
  327.            writes directly into the chunkymaps instead of using a temporary
  328.            buffer.
  329.  
  330.          - Added code which checks if it is possible to skip the
  331.            LockBitMap/UnLockBitMap protocoll. If it is possible (in the case
  332.            of CyberGFX), bitmaps are accessed througth (bm -> Planes[ 0 ])
  333.            directly.
  334.  
  335.          - Major speedup in the encoder. IMHO it is now twice as fast as
  336.            in V2.2...
  337.  
  338.        V2.4
  339.          - Fixed a bug which caused big trouble with CyberGFX.
  340.            Starting with V2.3, mpegvideo.datatype's decoder allocates
  341.            chunkypixel bitmaps with the ADTA_KeyBitMap as friend bitmap
  342.            (the RTG-software should be forced to allocate all bitmaps from
  343.            the same type/chunk of memory).
  344.            Due a missing BMF_MINPLANES CyberGFX returned a planar bitmap,
  345.            which wasn't expected here.
  346.            Changes to fix this bug:
  347.            - Set BMF_MINPLANES in AllocBitMap's flag field.
  348.            - The returned bitmap is tested using GetCyberMapAttr if
  349.              it has _really_ the requested pixelformat.
  350.            Thanks to Frank Mariak (fmariak@chaosengine.ping.de) for his
  351.            help...
  352.            Fixed.
  353.  
  354.          - The decoder now works with PIPE: as input again, as requested by 
  355.            many people. Still requires that the DataType is set by the
  356.            user because the datatypes.library file type identification code
  357.            (ObtainDataTypeA) does not work on non-seekable streams.
  358.            Usage:
  359.                GMultiView DATATYPE="MPEG Video" FILE="x.m1v"
  360.            Fixed.
  361.  
  362.          - Any attempt to use the NOLOADALL mode on a non-seekable stream
  363.            (PIPE: for example) now results in an error message and
  364.            forces the LOADALL mode.
  365.  
  366.          - Minor fixes in the autodocs.
  367.  
  368.        V2.5
  369.          - PPC version recompiled with SAS/C PPC beta 22.
  370.            - Minor fixes to match the new SAS/C ppc beta 22.
  371.  
  372.          - The PPC version now requires a mc68040 as "companion" processor.
  373.            This change was done because Phase5 dropped the m68030/PPC boards.
  374.  
  375.          - Found a serious bug in the #?ieee versions of mpegvideo.datatype
  376.            (e.g. 000ieee/ and 020ieee/) which seems to be present in all V2
  377.            versions...:
  378.            The startup code did not open mathieeedoubtrans.library, which is
  379.            used by the "sqrt" function in the dct table setup.
  380.            Thanks to Chris McVeigh (escom4@escom4.demon.co.uk) for reporting
  381.            the problem.
  382.            Fixed.
  383.  
  384.          - The p96.library is now opened before the cybergraphics.library
  385.            because the p96.library can be opened WITHOUT any gfx-card
  386.            present. This allows to get access to the 24-bit-chunky-bitmaps.
  387.            You may not be able to view them, but tools like "DTConvert"
  388.            may benefit from this...
  389.  
  390.          - The PPC-Version now checks ppc.library's revision field
  391.            (must be at least rev 13 (yet), current development was done with
  392.            ppc.library V45.20, V46 preferred), except the version field
  393.            is > V45. This fixes crashes if someone tries an earlier
  394.            version...
  395.            Fixed.
  396.  
  397.          - Added an alert (AN_Unknown + 0x531) and an endless loop in the
  398.            _XCEXIT stub code. This code should never be called, but if
  399.            the case occurs (should not, should not), the system won't crash
  400.            now. Only the application hangs, and a little bit informative
  401.            alert occurs.
  402.            Should never ever happen, but...
  403.  
  404.          - Big change in the PPC decoder launch: Instead of creating a
  405.            process per "frame decoding sequence" now the decoder starts one
  406.            ppc task at startup and sends the decoding jobs as messages to
  407.            it on demand. This is much more efficient and faster than the
  408.            old way.
  409.            Still experimental, but works.
  410.            The NOLOADALL mode (and the DITHERATPLAYBACKTIME option, too)
  411.            now makes much more fun...
  412.  
  413.          - The PPC code is now compiled with SAS/C's HUNKOBJ mode, which
  414.            makes the compilation/project build much easier...
  415.  
  416.          - DITHER=MONO_THRESHOLD now uses lum > 127 instead of lum > 128 as
  417.            the way to choose between black or white. Now both back and white
  418.            have the same range of values.
  419.            Another benefit is that the compiler maybe can use the change to
  420.            optimize the code much more...
  421.  
  422.          - Found and fixed the bug that the NOBFRAMES / NOPFRAMES options 
  423.            did not work.
  424.            Fixed.
  425.  
  426.          - NOBFRAMES / NOPFRAMES options are now compatible with the
  427.            NOLOADALL mode.
  428.  
  429.          - Changes in the encoder and encoder support code.
  430.            The encoder is now faster; it now reaches ~80% of the maximum
  431.            possible speed (the remaining 20% are (maybe) a victim of the
  432.            cacheflushed required for PPCCallOS calls :-(   ).
  433.  
  434.    NOTES
  435.        - Time-codes in the GOP are ignored - which isn't serious here
  436.          yet.
  437.  
  438.        - Not all parameters in a given "mpeg2enc"-like parameter file
  439.          are recognized by the encoder because the information is
  440.          directly got from the object (like width, height, copyright
  441.          info etc.).
  442.          Other things like scalability are not implemented yet.
  443.  
  444.    SEE ALSO
  445.        animation.datatype,
  446.        mpegsystem.datatype, mpegaudio.datatype
  447.        picmovie.datatype,
  448.        paranimdtcpatch
  449.  
  450. mpegvideo.datatype/ADTM_LOADFRAME           mpegvideo.datatype/ADTM_LOADFRAME
  451.  
  452.     NAME
  453.         ADTM_LOADFRAME -- Load frame
  454.  
  455.     FUNCTION
  456.         The ADTM_LOADFRAME method is used to obtain the bitmap and timing
  457.         data of the animation.
  458.         The given timestamp will be used to find the closest timestamp
  459.         in stream. If it was found, the corresponding timing, bitmap, 
  460.         colormap and sound data are stored into the struct adtFrame.
  461.         In NOLOADALL mode, missing frame data are dynamically loaded
  462.         from the stream.
  463.  
  464.     NOTE
  465.         In NOLOADALL mode mpegvideo.datatype always loads a
  466.         whole IPPB...I sequence into memory; the sequence stays in memory
  467.         until all frames of the sequence are unloaded.
  468.  
  469.     RESULT
  470.         Returns non-zero if the frame was loaded, 0UL otherwise
  471.         (Result2 (IoErr()) contains then the cause).
  472.  
  473. mpegvideo.datatype/ADTM_UNLOADFRAME       mpegvideo.datatype/ADTM_UNLOADFRAME
  474.  
  475.     NAME
  476.         ADTM_UNLOADFRAME -- Unload frame contents
  477.  
  478.     FUNCTION
  479.         The ADTM_UNLOADFRAME method is used to release the contents of a
  480.         animation frame.
  481.  
  482.         This method frees the bitmap data found in adtFrame.
  483.  
  484.     RESULT
  485.         Returns always 0UL.
  486.  
  487. mpegvideo.datatype/DTM_WRITE                     mpegvideo.datatype/DTM_WRITE
  488.  
  489.     NAME
  490.         DTM_WRITE -- Save data
  491.  
  492.     FUNCTION
  493.         This method saves the object's contents to disk.
  494.  
  495.         If dtw_Mode is DTWM_IFF, the method is passed unchanged to the
  496.         superclass (animation.datatype), which writes a single IFF ILBM
  497.         picture.
  498.         The local data format (e.g. dtw_Mode == DTWM_RAW) writes
  499.         a mpeg video stream, as set by the prefereces.
  500.  
  501.     RESULT
  502.         Returns 0 for failure (IoErr() returns result2), non-zero
  503.         for success.
  504.  
  505.     SEE ALSO
  506.         preferences section for encoder options
  507.  
  508. mpegvideo.datatype/MAIN                               mpegvideo.datatype/MAIN
  509.  
  510.     INTRODUCTION
  511.         Datatypes class for decoding/encoding MPEG Video streams (MPEG 1
  512.         and MPEG 2).
  513.  
  514.     REQUIREMENTS
  515.         - You need at least Kick/WB 3.0.
  516.  
  517.         - "datatypes/animation.datatype", >= V40 (V41 preferred)
  518.           which requires itself some libraries/boopsi classes:
  519.           - "realtime.library", >= V39              - for timing
  520.           - "gadgets/tapedeck.gadget" (any version) - for the controls
  521.  
  522.         - ppc.library >= V45 rev 13 for the PPC version
  523.           (It was developed with V45.20...)
  524.  
  525.         - 2 MB of memory (3 MB for the PPC version)
  526.  
  527.     USAGE
  528.         If the datatypes descriptor file was activated, any attempt to load
  529.         a MPEG Video stream using GMultiView, MultiView, AmigaGuide or
  530.         SwitchWindow will load and play the movie.
  531.  
  532.     INSTALLATION
  533.         After unpacking this archive:
  534.         Because this version does not include an Installer script, you have
  535.         to do the installation manually through the shell:
  536.  
  537.           - Unpack this archive and copy the "mpegvideo.datatype" to
  538.             SYS:Classes/DataTypes/:
  539.  
  540.         Copy CLONE FROM "mpegvideo.datatype" TO
  541.          "SYS:Classes/DataTypes/mpegvideo.datatype"
  542.  
  543.         The "mpegvideo.datatype" class library is available in different
  544.         versions for different cpu versions:
  545.  
  546.             directory  | cpu type (minimum requirements)
  547.             -----------+--------------------------------------
  548.             000ieee/   | m68000 using IEEE math library
  549.             020ieee/   | m68020 using IEEE math library
  550.             020881/    | m68020 using 68881 FPU
  551.             040881/    | m68040 using 68881 FPU emulation code
  552.             060881/    | m68060 using 68881 FPU emulation code
  553.             040ppc/    | m68040 and a PowerPC cpu
  554.  
  555.         Use the "C:CPU" shell command to check which m68k version you need.
  556.  
  557.           - Then copy the datatypes descriptor into the DEVS:DataTypes
  558.             directory.
  559.             If the descriptor already exists, you should not replace it,
  560.             otherwise you may loose "toolnodes" and other settings stored in
  561.             the existing descriptor.
  562.  
  563.      Copy CLONE FROM "MPEG Video(%|.info)" TO DEVS:Datatypes/
  564.  
  565.     NOTES
  566.         Both encoder and decoder loosely based on "mpeg2dec" and "mpeg2enc"
  567.         of the MSSG. See http://www.mpeg.org.
  568.  
  569.     AUTHOR
  570.         If you want to blame me, report any bugs, or wants a new version
  571.         send your letter to:
  572.                         Roland Mainz
  573.                         Hohenstaufenstraße 8
  574.                         52388 Nörvenich
  575.                         GERMANY
  576.  
  577.         Phone: (+49)(0)2426/901568
  578.         Fax:   (+49)(0)2426/901569
  579.  
  580.         EMAIL is also available (if you want to send me attachments
  581.         larger than 1MB (up to 5MB, more with my permission):
  582.  
  583.         GISBURN@w-specht.rhein-ruhr.de
  584.  
  585.         Up to August 1998 I'm reachable using this email address, too:
  586.         Reinhold.A.Mainz@KBV.DE
  587.  
  588.         | Please put your name and address in your mails !
  589.         | German mailers should add their phone numbers.
  590.         | See BUGS section above when submitting bug reports.
  591.  
  592.         Sorry, but I can only look once a week for mails.
  593.         If you don't hear something from me within three weeks, please
  594.         send your mail again (but watch about new releases) (problems with
  595.         this email port are caused by reconfigurations, hackers, network
  596.         problems etc.).
  597.  
  598.         The  entire  "mpegvideo.datatype"  package  may  be  noncommercially
  599.         redistributed, provided  that  the package  is always  distributed
  600.         in it's complete  form (including it's documentation). A small
  601.         copy fee  for media costs is okay but any kind of commercial
  602.         distribution is strictly forbidden without my permission !
  603.         Comments and suggestions how to improve this program are
  604.         generally appreciated!
  605.  
  606.         Thanks to David Junod, who wrote the animation.datatype and lots of
  607.         the datatypes example code, Matt Dillon for his DICE,
  608.         Olaf 'Olsen' Barthel and Frank Mariak for their help, Phase5 for
  609.         their PPC board.
  610.  
  611. mpegvideo.datatype/OM_DISPOSE                   mpegvideo.datatype/OM_DISPOSE
  612.  
  613.     NAME
  614.         OM_DISPOSE -- Delete a mpegvideo.datatype object.
  615.  
  616.     FUNCTION
  617.         The OM_DISPOSE method is used to delete an instance of the
  618.         mpegvideo.datatype class.  This method is passed to the superclass
  619.         when it has completed.
  620.         This method frees all frame nodes and their contents (pictures, their
  621.         colormaps, sounds etc.).
  622.  
  623.     NOTE
  624.         This method preserved Result2 (IoErr()).
  625.  
  626.     RESULT
  627.         The object is deleted. 0UL is returned.
  628.  
  629. mpegvideo.datatype/OM_NEW                           mpegvideo.datatype/OM_NEW
  630.  
  631.     NAME
  632.         OM_NEW -- Create a mpegvideo.datatype object.
  633.  
  634.     FUNCTION
  635.         The OM_NEW method is used to create an instance of the
  636.         mpegvideo.datatype class.  This method is passed to the superclass
  637.         first. After this, mpegvideo.datatype loads it's preference file
  638.         (and the sound file, if one was specified) and starts it work on
  639.         the video stream (load frames or scan stream for index information).
  640.         Any fatal error aborts the load, non-serious errors are reported.
  641.  
  642.     ATTRIBUTES
  643.         The following attributes can be specified at creation time.
  644.  
  645.         DTA_SourceType (ULONG) -- Determinates the type of DTA_Handle
  646.             attribute. Both DTST_FILE and DTST_RAM are supported.
  647.             If any other type was set in a given DTA_SourceType,
  648.             OM_NEW will be rejected with result2 == ERROR_OBJECT_WRONG_TYPE.
  649.             Defaults to DTST_FILE.
  650.  
  651.         DTA_Handle (BPTR) -- If DTA_SourceType is DTST_FILE, the given file
  652.             handle will be used as an mpeg video stream to read in.
  653.             DTST_RAM requires that this tag data is NULL !
  654.  
  655.     RESULT
  656.         If the object was created a pointer to the object is returned,
  657.         otherwise NULL is returned.
  658.  
  659. mpegvideo.datatype/preferences                 mpegvideo.datatype/preferences
  660.  
  661.    NAME
  662.        preferences
  663.  
  664.    DESCRIPTION
  665.        The "ENV:Classes/DataTypes/mpegvideo.prefs" file contains global
  666.        settings for the datatype.
  667.        The preferences file is an ASCII file containing one line where the
  668.        preferences can be set.
  669.        It can be superset by a local variable with the same name.
  670.  
  671.        Each line can contain settings, special settings for some projects
  672.        can be set using the MATCHPROJECT option.
  673.        Lines beginning with a '#' or ';' chars are treated as comments.
  674.        Lines are limitted to 256 chars.
  675.  
  676.    TEMPLATE
  677.        MATCHPROJECT/K,DEVICE=MPEGDEVICE/K,UNIT=MPEGDEVICEUNIT/K/N,
  678.        MODEID/K/N,WIDTH/K/N,HEIGHT/K/N,DEPTH/K/N,DITHER/K,
  679.        LUM_RANGE/K/N,CR_RANGE/K/N,CB_RANGE/K/N,COLORERROR/K/N,
  680.        PALETTEPERFRAME/S,NOPALETTEPERFRAME/S,GAMMACORRECT/K,CHROMACORRECT/K,
  681.        MAXFRAME/K/N,SKIPFRAMES/K/N,FPS/K/N,PFRAMES/S,NOPFRAMES/S,
  682.        BFRAMES/S,NOBFRAMES/S,DITHERATPLAYBACKTIME/S,
  683.        NODITHERATPLAYBACKTIME/S,SAMPLE/K,VOLUME/K/N,BUFFER/K/N,LOADALL/S,
  684.        NOLOADALL/S,USEVMM/S,NOUSEVMM/S,MINTOTALMEM/K/N,IGNOREERRORS/S,
  685.        VERBOSE/S,__VERBOSELEVEL/K/N,TRACE/S,NOTRACE/S,PROGRESSGAUGE/S,
  686.        NOPROGRESSGAUGE/S,QUALITY/S,NOQUALITY/S,ENCODERPARAMETERS=PARFILE/K,
  687.        ENC_REALLOC_LOADFRAME/S,ENC_NO_REALLOC_LOADFRAME/S,
  688.        ENC_RECONSTRUCTED_IMAGES/K,ENC_INTRA_QUANT_MAXTRIX_FILE/K,
  689.        ENC_NON_INTRA_QUANT_MAXTRIX_FILE/K,ENCODERLOG=ENCODERSTATISTICS/K,
  690.        ENC_FIRSTFRAME/K/N,ENC_START_TIMECODE/K,ENC_NUM_GOP_FRAMES/K/N,
  691.        ENC_I_P_FRAME_DIST/K/N,ENC_FORCE_MPEG1/S,ENC_FIELD_PICTURES/S,
  692.        ENC_FRAME_PICTURES/S,ENC_ASPECT_RATIO_INFORMATION/K,
  693.        ENC_FRAME_RATE/K,ENC_BIT_RATE/K,ENC_VBV_BUFFER_SIZE/K/N,
  694.        ENC_CONSTRAINED_PARAMETERS_FLAG/S,
  695.        ENC_NO_CONSTRAINED_PARAMETERS_FLAG/S,
  696.        ENC_PROFILE_ID/K,ENC_LEVEL_ID/K,ENC_PROGRESSIVE_SEQUENCE/S,
  697.        ENC_NOPROGRESSIVE_SEQUENCE/S,ENC_CHROMA_FORMAT/K,ENC_VIDEO_FORMAT/K,
  698.        ENC_COLOR_PRIMARIES/K,ENC_TRANSFER_CHARACTERISTICS/K,
  699.        ENC_MATRIX_COEFFICIENTS/K,ENC_INTRA_DC_PRECISION/K,
  700.        ENC_TOP_FIELD_FIRST=ENC_ODD_FIELD_FIRST/S,
  701.        ENC_BOTTOM_FIELD_FIRST=ENC_EVEN_FIELD_FIRST/S,
  702.        ENC_FRAME_PRED_FRAME_DCT_I/S,ENC_NO_FRAME_PRED_FRAME_DCT_I/S,
  703.        ENC_FRAME_PRED_FRAME_DCT_P/S,ENC_NO_FRAME_PRED_FRAME_DCT_P/S,
  704.        ENC_FRAME_PRED_FRAME_DCT_B/S,ENC_NO_FRAME_PRED_FRAME_DCT_B/S,
  705.        and so on...
  706.  
  707.        MATCHPROJECT -- The settings in this line belongs only to this
  708.            project(s), e.g. if the case-insensitive pattern does not match,
  709.            this line is ignored.
  710.            The maximum length of the pattern is 128 chars.
  711.            Defaults to #?, which matches any project.
  712.  
  713.        DEVICE
  714.        MPEGDEVICE -- If the Amiga has a "cd32mpeg.device" compatible device
  715.            which supports the MPEGCMD_READFRAMEYUV device command, 
  716.            mpegvideo.datatype cam use this device for decoding
  717.            (which may limit to MPEG-1).
  718.            EXPERIMENTAL. UNTESTED. But should work...
  719.  
  720.        UNIT
  721.        MPEGDEVICEUNIT - Selects the unit of the mpeg decoder device.
  722.            Should only be set if you know what you're doing...
  723.  
  724.        MODEID -- Select screen mode id of datatype (will be stored in
  725.            ADTA_ModeID). Note that the DOS ReadArgs function used for parsing
  726.            fetches a SIGNED long. The bit 31 will be represented by minus
  727.            '-'. (example: "MODEID=266240" sets the mode to the A2024 screen
  728.            mode id)
  729.            Defaults to -1, which means: Use the best screenmode available
  730.            for the given width, height and depth.
  731.  
  732.        WIDTH -- Set the animation's width. The video will be scaled to this
  733.            width.
  734.            Defaults to 0, which means: Use video's width.
  735.  
  736.        HEIGHT -- Set the animation's height. The video will be scaled to this
  737.            height.
  738.            Defaults to 0, which means: Use video's height.
  739.  
  740.        DEPTH -- depth for the selected scaling mode
  741.            A value describing the "depth" of the animation.
  742.            1 upto 8 are valid, under- or overflows will be truncated
  743.            to the maximum supported.
  744.            The default depth will be selected by the DITHER mode.
  745.  
  746.        DITHER -- dither type, one of
  747.            MONO            -- monocrome output, 1 bit
  748.            MONO_THRESHOLD  -- monocrome output with threshold, 1 bit
  749.            GRAY            -- grayscale output (broken in V2.1)
  750.            HAM             -- ham ham6/ham8 etc. (default)
  751.            EHB             -- extra halfbright (broken in V2.1)
  752.            COLOR           -- color output (broken in V2.1)
  753.            ORDERED         -- ordered dither
  754.            24BITCHUNKY     -- true color, 24 bit
  755.            16BITCHUNKY     -- true color, 16 bit
  756.            24BITPLANAR     -- true color, 24 bit
  757.            YUV420          -- YUV420 bitmap
  758.  
  759.            MONO
  760.            MONO_THRESHOLD -- Monocrome output modes, both in two
  761.                colors (black/white).
  762.  
  763.            GRAY is the grayscale mode.
  764.                If no depth is given, the depth default to 5 (32 colors).
  765.  
  766.            HAM (hold-and-modify) mode: Either HAM6 or HAM8, set by the depth
  767.                option. If no depth is given, this defaults to 6 for OCS/ECS
  768.                and 8 for AGA/AAA machines.
  769.                This is the default dither mode if no DITHER option is given.
  770.  
  771.            EHB (extra halfbright mode):
  772.                If no depth is given, the depth default to 6 (32/64 colors).
  773.                not implemented yet
  774.  
  775.            COLOR remaps the frames into a fixed color space.
  776.                If no depth is given, the depth default to 8 (256 colors).
  777.  
  778.            ORDERED uses ordered dithering.
  779.                If no depth is given, the depth default to 8 (256 colors).
  780.  
  781.            24BITCHUNKY uses chunkypixel CyberGFX bitmaps
  782.                Fixed to a depth of 32 (XRGB).
  783.                Requires at least animation.datatype V41.3.
  784.  
  785.            16BITCHUNKY uses chunkypixel CyberGFX bitmaps
  786.                Fixed to a depth of 16 (XRGB).
  787.                Requires at least animation.datatype V41.3.
  788.  
  789.            24BITPLANAR uses a planar 24 bit depth bitmap (non-interleaved)
  790.                Fixed to a depth of 24 (RGB).
  791.                Requires at least animation.datatype V41.3.
  792.  
  793.            YUV420 uses a Picasso96 YUV bitmap.
  794.                Experimental. Not tested yet. Currently limitted to MPEG-1.
  795.                Requires a newer Picasso96 version which supports remapping
  796.                YUV -> RGB bitmaps, otherwise you don't see any display.
  797.                Requires at least animation.datatype V41.3.
  798.  
  799.            Defaults to HAM.
  800.  
  801.        LUM_RANGE -- sets the number of colors assigned to the luminance
  802.            component when dithering the image.  The product of LUM_RANGE,
  803.            CR_RANGE and CB_RANGE should be less than the number of colors
  804.            selected by the DEPTH option.
  805.            This will only affect ORDERED and COLOR dithering and the base
  806.            palette of the DICECOLOR remapping.
  807.            Any value between 1 upto 255 is allowed, 0 is treated as 1.
  808.  
  809.            Defaults: see DEFAULTS section below
  810.  
  811.        CR_RANGE -- sets the number of colors assigned to the red component of
  812.            the chrominace range when dithering the image.  The product of
  813.            LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of
  814.            colors selected by the DEPTH option.
  815.            This will only affect ORDERED and COLOR dithering and the base
  816.            palette of the DICECOLOR remapping.
  817.            Any value between 1 upto 255 is allowed, 0 is treated as 1.
  818.  
  819.            Defaults: see DEFAULTS section below
  820.  
  821.        CB_RANGE -- sets the number of colors assigned to the blue component
  822.            of the chrominace range when dithering the image.  The product of
  823.            LUM_RANGE, CR_RANGE and CB_RANGE should be less than the number of
  824.            colors selected by the DEPTH option.
  825.            This will only affect ORDERED and COLOR dithering and the base
  826.            palette of the DICECOLOR remapping.
  827.            Any value between 1 upto 255 is allowed, 0 is treated as 1.
  828.  
  829.            Defaults: see DEFAULTS section below
  830.  
  831.        COLORERROR -- Set the error range when allocating colors.
  832.            The error range is used for color matching
  833.            (like this: if( ABS( (pixel . red) - (colormap . red) ) +
  834.                        ABS( <dito. green> ) + ABS( <dito. blue> )
  835.                        < colorerror ) then use this color index).
  836.            A low value (0) means high quality remapping and slow remapping,
  837.            high values (50) means low quality (using less color indexes).
  838.  
  839.            Defaults to 0.
  840.  
  841.        PALETTEPERFRAME -- Create a own palette for each frame.
  842.            __Currently__ a NOP for HAM dithering and always a NOP
  843.            for all direct-RGB output modes (24BITCHUNKY, 16BITCHUNKY,
  844.            24BITPLANAR).
  845.  
  846.            Note that this option requires animation.datatype V41 to work.
  847.  
  848.        NOPALETTERPERFRAME -- Turns PALETTEPERFRAME switch off.
  849.  
  850.        GAMMACORRECT -- Gamma correction value (defined as fixed point
  851.            number).
  852.            Defaults to "1.0".
  853.  
  854.        CHROMACORRECT -- Chroma correction value (defined as fixed point
  855.            number).
  856.            Defaults to "1.0".
  857.  
  858.        MAXFRAME -- Maximum number of frames to load.
  859.            Defaults to 0, which means: Load all frames.
  860.  
  861.        SKIPFRAMES -- Load only the n-th frame of an animation.
  862.            The internal timing (e.g. time code) is not affected, so
  863.            the FPS value will be correct.
  864.            Defaults to 0 which means: Skip no frame.
  865.  
  866.            Note that this option requires animation.datatype V41 to work
  867.            properly.
  868.  
  869.        FPS -- frames per second
  870.            Defaults to 0, which means: overtake fps rate from video stream.
  871.            Setting the FPS value also affects an attched sound. The period
  872.            of the sample (e.g. the playback speed) will everytimes as long
  873.            as the frame is displayed.
  874.  
  875.        PFRAMES -- Turns off the NOPFRAMES option.
  876.            Default is on.
  877.  
  878.        NOPFRAMES -- ignore any type P frames (predicted frames) when loading.
  879.  
  880.        BFRAMES -- Turns off the NOBFRAMES option.
  881.            Default is on.
  882.  
  883.        NOBFRAMES -- ignore any type B frames (bidirectional frames) when
  884.            loading.
  885.            Default is off.
  886.  
  887.        DITHERATPLAYBACKTIME -- YUV -> RGB dithering is done at playback
  888.            (ADTM_LOADFRAME) time.
  889.            This saves time during decoding (LOADALL mode) and causes
  890.            smoother loading on NOLOADALL mode. But only a mc68040 or higher
  891.            should use this option.
  892.            This option is also neccesary if you use CyberGFX output modes
  893.            and wants to use VMM (CyberGFX bitmaps cannot be in VMM memory,
  894.            but the YUV data can be there...).
  895.  
  896.        NODITHERATPLAYBACKTIME -- Turns the DITHERATPLAYBACKTIME option off.
  897.  
  898.        SAMPLE -- Attach the given sample to the animation. The sample will
  899.            be loaded using datatypes (GID_SOUND).
  900.            Only one sample can be attached to one video stream, any following
  901.            attempt to attach the sample will be ignored.
  902.  
  903.            Default: no sample
  904.  
  905.        VOLUME -- Volume of the sound when playing.
  906.            Defaults to 63, which is the maximum. A value greater than 64 will
  907.            be set to 63.
  908.  
  909.        BUFFER -- read buffers size. Minimum is 2048, lower values are set to
  910.            2048.
  911.            Defaults to 0.5% of the file size, but at least 2048 and max.
  912.            16384 bytes.
  913.  
  914.        LOADALL -- load all frames before displaying it.
  915.  
  916.        NOLOADALL -- turns off LOADALL switch (decode during playback).
  917.  
  918.        USEVMM -- Use Martin Apel's vmm.library for bitmaps.
  919.            The verbose output will tell you if VMM memory will be used or
  920.            not.
  921.            The DITHERATPLAYBACKTIME option is required if you use
  922.            CyberGFX output modes and wants to use VMM (CyberGFX bitmaps 
  923.            cannot be in VMM memory, but the YUV data can be there...).
  924.            Default is off.
  925.  
  926.        NOUSEVMM -- Turn VMM usage for bitmaps off.
  927.  
  928.        MINTOTALMEM -- Minimum total memory available. If less memory
  929.            available, abort loading.
  930.            Defaults to 0, which means: Don't use this option.
  931.  
  932.        IGNOREERRORS -- Ignore errors while parsing/decoding etc.
  933.            Usefull if a syntax error or read error (which may occur with
  934.            some old, buggy CD filesystems) happens.
  935.            Default is off.
  936.  
  937.        VERBOSE -- Verbose output. Prints out current frame etc., some
  938.            statistical information and maybe, debugging infos.
  939.            Verbose output will be printed in a console window
  940.            ("CON://///auto/wait/close/inactive/MPEG Video DataType").
  941.            Default is off.
  942.  
  943.        PROGRESSGAUGE -- Display a load progress gauge.
  944.            Default is on.
  945.  
  946.        NOPROGRESSGAUGE -- Disables the progress gauge which is displayed
  947.            during loading of the mpeg stream.
  948.            Default is off.
  949.  
  950.        QUALITY -- If set, mpegvideo.datatype uses floating-point dct
  951.            decoding, which results in a better output quality.
  952.            (broken in V2.1)
  953.            Default is off.
  954.  
  955.        NOQUALITY -- Turns QUALITY switch off.
  956.            Default is on.
  957.  
  958.        And here comes the encoder options:
  959.  
  960.        ENCODERPARAMETERS
  961.        PARFILE -- "mpeg2enc" like encoder parameters file
  962.            Note that some options (like width/height) are ignored.
  963.  
  964.        ENC_REALLOC_LOADFRAME -- Enables "realloc"-like loading from
  965.            souce object. This option allows that a ADTM_LOADFRAME
  966.            from the source object can reuse data from a previous
  967.            ADTM_LOADFRAME call.
  968.            This option is on per default.
  969.  
  970.        ENC_NO_REALLOC_UNLOADFRAME -- Disables "realloc"-like loading from
  971.            source object.
  972.            This option was introduced for debugging and should not
  973.            be set, otherwise loading from the source object may be much
  974.            slower.
  975.  
  976.        ENC_RECONSTRUCTED_IMAGES --
  977.            This user parameter tells the encoder what name to give the
  978.            reconstructed frames. These frames are identical to frame
  979.            reconstructions of decoders following normative guidelines
  980.            (except of course for differences caused by different IDCT
  981.            implementation).
  982.            The reconstructed frames are always stored in Y,U,V format.
  983.  
  984.        ENC_INTRA_QUANT_MAXTRIX_FILE --  This option specifies a file
  985.            containing a custom intra quantization matrix to be used instead
  986.            of the default matrix specified in ISO/IEC 13818-2 and 
  987.            11172-2. This file has to contain 64 integer values 
  988.            (range 1...255) separated by white space (blank, tab, or
  989.            newline), one corresponding  to each of the 64 DCT coefficients. 
  990.            They are ordered line by line, i.e. v-u frequency matrix order
  991.            (not by the zig-zag pattern used for transmission). The example 
  992.            file "intra.mat" contains the default matrix as a starting point 
  993.            for customization. It is neither necessary or recommended to
  994.            specify the default matrix explicitly.
  995.  
  996.            Large values correspond to coarse quantization and consequently 
  997.            more noise at that particular spatial frequency.
  998.  
  999.            For the intra quantization matrix, the first value in the file 
  1000.            (DC value) is ignored. Use the parameter intra_dc_precision (see 
  1001.            below) to define the quantization of the DC value.
  1002.  
  1003.        ENC_NON_INTRA_QUANT_MAXTRIX_FILE -- This option follows the same
  1004.            rules as described for the above intra quant matrix parameter,
  1005.            but specifies the file for the NON-INTRA coded (predicted /
  1006.            interpolated) blocks. In this case the first coefficient of the
  1007.            matrix is NOT ignored.
  1008.  
  1009.            The default matrix uses a constant value of 16 for all 64 
  1010.            coefficients. (a flat matrix is thought to statistically minimize 
  1011.            mean square error).
  1012.            The example file "inter.mat" contains an alternate matrix, used
  1013.            in the MPEG-2 test model.
  1014.  
  1015.        ENC_START_TIMECODE -- This option is used to set the timecode encoded
  1016.            into the first 'Group of Pictures' header. The format is based
  1017.            on the SMPTE style:
  1018.  
  1019.            hh:mm:ss:ff (hh=hour, mm=minute, ss=second, ff=frame
  1020.            (0..picture_rate-1)
  1021.  
  1022.        ENC_NUM_GOP_FRAMES --  This option defines the distance between I
  1023.            frames (and 'Group of Pictures' headers). Common values are 15
  1024.            for 30 Hz video and 12 for 25 Hz video.
  1025.  
  1026.        ENC_I_P_FRAME_DIST -- Distance between consecutive I or P frames.
  1027.            Usually set to 3. ENC_NUM_GOP_FRAMES has to be a multiple of
  1028.            ENC_I_P_FRAME_DIST.   ENC_I_P_FRAME_DIST = 1 means no B
  1029.            frames in the sequence. (in a future edition of this program,
  1030.            ENC_I_P_FRAME_DIST=0 will mean only I frames).
  1031.  
  1032.        ENC_FORCE_MPEG1 -- Set this switch if you want to generate an MPEG-1
  1033.            sequence. In this case some of the subsequent MPEG-2 specific
  1034.            values are ignored.
  1035.  
  1036.        ENC_FIELD_PICTURES -- Selects frame picture coding, in which both
  1037.            fields of a frame are coded simultaneously.
  1038.            This switch is the reverse of the ENC_FRAME_PICTURES switch.
  1039.  
  1040.        ENC_FRAME_PICTURES -- Select field picture coding, where fields are
  1041.            coded separately. This option is permitted for interlaced
  1042.            video only.
  1043.            This switch is the reverse of the ENC_FIELD_PICTURES switch.
  1044.  
  1045.        ENC_ASPECT_RATIO_INFORMATION -- Defines the display aspect ratio.
  1046.            One of SQUARE_PELS or 1_1_DISPLAY or CODE_1
  1047.                   4_3_DISPLAY                or CODE_2
  1048.                   16_9_DISPLAY               or CODE_3
  1049.                   2_21_1_DISPLAY             or CODE_4
  1050.  
  1051.            MPEG-1 uses a different coding of aspect ratios. In this cases 
  1052.            codes CODE_1 to CODE_14 are valid.
  1053.  
  1054.        ENC_FRAME_RATE -- Defines the frame rate (for interlaced sequences: 
  1055.            field rate is twice the frame rate).
  1056.  
  1057.            Frames/sec    Meaning
  1058.            ----------    -----------------------------------------------
  1059.            24000/1001    23.976 fps -- NTSC encapsulated film rate
  1060.            24            Standard international cinema film rate
  1061.            25            PAL (625/50) video frame rate
  1062.            30000/1001    29.97 -- NTSC video frame rate
  1063.            30            NTSC drop-frame (525/60) video frame rate
  1064.            50            double frame rate/progressive PAL
  1065.            60000/1001    double frame rate NTSC
  1066.            60            double frame rate drop-frame NTSC
  1067.  
  1068.            one of
  1069.            ----------+----------+---------------------------------------
  1070.            24000_1001|23_976_FPS|NTSC_ENCAPSULATED_FILM_RATE
  1071.            24        |24_FPS    |STANDARD_INTERNATIONAL_CINEMA_FILM_RATE
  1072.            25        |25_FPS    |PAL_VIDEO_FRAME_RATE
  1073.            30000_1001|29_97_FPS |NTSC_VIDEO_FRAME_RATE
  1074.            30        |30_FPS    |NTSC_DROP_FRAME_VIDEO_FRAME_RATE
  1075.            50        |50_FPS    |DOUBLE_FRAME_RATE or PROGRESSIVE_PAL
  1076.            60000_1001|59_94_FPS |DOUBLE_FRAME_RATE_NTSC
  1077.            60        |60_FPS    |DOUBLE_FRAME_RATE_DROP_FRAME_NTSC
  1078.            15        |15_FPS    |XING_RATE
  1079.  
  1080.            Or CODE_1 upto CODE_9.
  1081.  
  1082.            Note that the XING code 9 with 15 fps is not implemented yet.
  1083.  
  1084.        ENC_BIT_RATE -- A positive floating point value specifying the
  1085.            target bitrate. In units of bits/sec.
  1086.  
  1087.        ENC_VBV_BUFFER_SIZE --  Specifies, according to the Video Buffering 
  1088.            Verifier decoder model, the size of the bitstream input buffer 
  1089.            required in downstream decoders in order for the sequence to be 
  1090.            decoded without underflows or or overflows.  You probably will
  1091.            wish to leave this value at 112 for MPEG-2 Main Profile at Main 
  1092.            Level, and 20 for Constrained Parameters Bitstreams MPEG-1.
  1093.  
  1094.        ENC_CONSTRAINED_PARAMETERS_FLAG -- Set this switch if you encode an
  1095.            MPEG-1 sequence which meets the parameter limits defined in
  1096.            ISO/IEC 11172-2 for constrained parameter bitstreams:
  1097.            horizontal_size <= 768
  1098.            vertical_size   <= 576
  1099.            picture_area    <= 396 macroblocks
  1100.            pixel_rate      <= 396x25 macroblocks per second
  1101.            vbv_buffer_size <= 20x16384 bit
  1102.            bitrate         <= 1856000 bits/second
  1103.            motion vector range <= -64...63.5
  1104.  
  1105.        ENC_NO_CONSTRAINED_PARAMETERS_FLAG -- Turns the 
  1106.            ENC_CONSTRAINED_PARAMETERS_FLAG off; 
  1107.            set this option always for MPEG-2 !
  1108.  
  1109.        ENC_PROFILE_ID -- Specifies the subset of the MPEG-2 syntax required 
  1110.            for decoding the sequence. All MPEG-2 sequences generated by the
  1111.            current version of the encoder are either Main Profile or Simple
  1112.            Profile sequences.
  1113.  
  1114.            one of RESERVED_0
  1115.                   HIGH
  1116.                   SPATIALLY  or  SPATIALLY_SCALABLE
  1117.                   SNR        or  SNR_SCALABLE
  1118.                   MAIN
  1119.                   SIMPLE
  1120.                   RESERVED_6
  1121.                   RESERVED_7
  1122.                   RESERVED_8
  1123.                   RESERVED_9
  1124.                   RESERVED_10
  1125.                   RESERVED_11
  1126.                   RESERVED_12
  1127.                   RESERVED_13
  1128.                   RESERVED_14
  1129.                   RESERVED_15
  1130.  
  1131.            Or use CODE_0 up to CODE_15.
  1132.  
  1133.        ENC_LEVEL_ID -- Specifies coded parameter constraints, such as 
  1134.            bitrate, sample rate, and maximum allowed motion vector range.
  1135.  
  1136.            one of RESERVED_0
  1137.                   RESERVED_1
  1138.                   RESERVED_2
  1139.                   RESERVED_3
  1140.                   HIGH
  1141.                   RESERVED_5
  1142.                   HIGH_1440
  1143.                   RESERVED_7
  1144.                   MAIN
  1145.                   RESERVED_9
  1146.                   LOW
  1147.                   RESERVED_11
  1148.                   RESERVED_12
  1149.                   RESERVED_13
  1150.                   RESERVED_14
  1151.                   RESERVED_15
  1152.  
  1153.            Or use CODE_0 upto CODE_15.
  1154.  
  1155.        ENC_PROGRESSIVE_SEQUENCE --  Set this switch for progressive video
  1156.            (e.g. film source).
  1157.            This switch is the reverse of the ENC_NOPROGRESSIVE_SEQUENCE
  1158.            switch.
  1159.  
  1160.        ENC_NOPROGRESSIVE_SEQUENCE -- Set this switch in the case of a
  1161.            sequences containing interlaced video (e.g. video camera source).
  1162.            This switch is the reverse of the ENC_PROGRESSIVE_SEQUENCE
  1163.            switch.
  1164.  
  1165.        ENC_CHROMA_FORMAT -- Specifies the resolution of chrominance data
  1166.            one of 420, 422, or 444.
  1167.            Or use CODE_1, CODE_2, CODE_3.
  1168.  
  1169.        ENC_VIDEO_FORMAT -- Specifies the video format
  1170.            One of COMP, PAL, NTSC, SECAM, MAC, UNSPEC
  1171.            Or use CODE_0 upto CODE_5.
  1172.  
  1173.        ENC_COLOR_PRIMARIES -- Specifies the x, y chromaticity coordinates of 
  1174.            the source primaries.
  1175.  
  1176.            One of ITU-R_Rec._709
  1177.                   unspecified
  1178.                   ITU-R_Rec._624-4_System_M
  1179.                   ITU-R_Rec._624-4_System_B_G
  1180.                   SMPTE_170M
  1181.                   SMPTE_240M
  1182.  
  1183.            Or use CODE_1 up to CODE_7.
  1184.  
  1185.        ENC_TRANSFER_CHARACTERISTICS -- Specifies the opto-electronic transfer
  1186.            characteristic of the source picture.
  1187.  
  1188.            One of ITU-R_Rec._709
  1189.                   unspecified
  1190.                   ITU-R_Rec._624-4_System_M
  1191.                   ITU-R_Rec._624-4_System_B_G
  1192.                   SMPTE_170M
  1193.                   SMPTE_240M
  1194.                   LINEAR_TRANSFER_CHARACTERISTICS
  1195.  
  1196.            Or use CODE_1 up to CODE_8.
  1197.  
  1198.        ENC_MATRIX_COEFFICIENTS -- Specifies the matrix coefficients used in
  1199.            deriving luminance and chrominance signals from the green,
  1200.            blue, and red primaries.
  1201.            One of ITU-R_Rec._709
  1202.                   unspecified
  1203.                   FCC
  1204.                   ITU-R_Rec._624-4_System_B_G
  1205.                   SMPTE_170M
  1206.                   SMPTE_240M
  1207.  
  1208.            Or use CODE_1 up to CODE_7.
  1209.  
  1210.        ENC_INTRA_DC_PRECISION -- Specifies the effective precision of the
  1211.            DC coefficient in MPEG-2 intra coded macroblocks. 10-bits usually 
  1212.            achieves quality saturation.
  1213.  
  1214.            One of 8, 9, 10, 11 or 8_BIT, 9_BIT and so on...
  1215.            Or use CODE_0 up to CODE_3.
  1216.  
  1217.  
  1218.        ENC_TOP_FIELD_FIRST 
  1219.        ENC_ODD_FIELD_FIRST -- Specifies that the top fields of an interlaced
  1220.            frame comes earlier. The top field corresponds to what is often
  1221.            called the "odd field," and the bottom field is also sometimes
  1222.            called the "even field."
  1223.            This switch is the revers of the ENC_BOTTOM_FIELD_FIRST option.
  1224.  
  1225.        ENC_BOTTOM_FIELD_FIRST
  1226.        ENC_EVEN_FIELD_FIRST -- Specifies that the bottom fields of an
  1227.            interlaced frame comes earlier. The top field corresponds to what
  1228.            is often called the "odd field," and the bottom field is also
  1229.            sometimes called the "even field."
  1230.            This switch is the revers of the ENC_BOTTOM_FIELD_FIRST option.
  1231.  
  1232.        ENC_FRAME_PRED_FRAME_DCT_I -- Setting this parameter restricts motion
  1233.            compensation to frame prediction and DCT to frame DCT.
  1234.  
  1235.        ENC_NO_FRAME_PRED_FRAME_DCT_I -- Turns ENC_FRAME_PRED_FRAME_DCT_I off.
  1236.  
  1237.        ENC_FRAME_PRED_FRAME_DCT_P -- Setting this parameter restricts motion
  1238.            compensation to frame prediction and DCT to frame DCT.
  1239.  
  1240.        ENC_NO_FRAME_PRED_FRAME_DCT_P -- Turns ENC_FRAME_PRED_FRAME_DCT_P off.
  1241.  
  1242.        ENC_FRAME_PRED_FRAME_DCT_B -- Setting this parameter restricts motion
  1243.            compensation to frame prediction and DCT to frame DCT.
  1244.  
  1245.        ENC_NO_FRAME_PRED_FRAME_DCT_B  -- Turns ENC_FRAME_PRED_FRAME_DCT_B 
  1246.            off.
  1247.  
  1248.    DEFAULTS
  1249.        Defaults for the options are noted above.
  1250.  
  1251.        LUM_RANGE, CR_RANGE, CB_RANGE options have defaults based on the
  1252.        depth:
  1253.  
  1254.        depth | LUM_RANGE | CR_RANGE | CB_RANGE | comment
  1255.        ------+-----------+----------+----------+----------------------
  1256.           8  |         7 |        6 |       6  | color output
  1257.           7  |         5 |        5 |       5  | color output
  1258.           6  |         4 |        4 |       4  | color output
  1259.           5  |         3 |        3 |       3  | color output
  1260.           4  |        16 |        1 |       1  | grayscale output
  1261.           3  |         8 |        1 |       1  | grayscale output
  1262.           2  |         4 |        1 |       1  | grayscale output
  1263.           1  |         2 |        1 |       1  | black & white output
  1264.  
  1265.    NOTE
  1266.        An invalid prefs file line will force the default settings for this
  1267.        line and the VERBOSE option.
  1268.  
  1269.    BUGS
  1270.        - Low memory may cause that the prefs file won't be parsed.
  1271.  
  1272.        - Lines are limitted to 256 chars
  1273.  
  1274.    SEE ALSO
  1275.        mssg/mpeg2enc.doc
  1276.  
  1277.